include: zephyr: APIs doc: fix Doxygen \retval command usage #98324
Conversation
Fix how Doxygen special commands \retval & \return are used in doc text. \retval: Starts a description for a function's return value with name <return value>, which needs to be attached and to not be a word that is part of the sentence, and each return val should have its own \retval. Otherwise \retval is replaced with \return. Signed-off-by: Abderrahmane JARMOUNI <[email protected]>
Fix how Doxygen special commands \retval & \return are used in doc text. \retval: Starts a description for a function's return value with name <return value>, which needs to be attached and to not be a word that is part of the sentence, and each return val should have its own \retval. Otherwise \retval is replaced with \return. Signed-off-by: Abderrahmane JARMOUNI <[email protected]>
Fix how Doxygen special commands \retval & \return are used in doc text. \retval: Starts a description for a function's return value with name <return value>, which needs to be attached and to not be a word that is part of the sentence, and each return val should have its own \retval. Otherwise \retval is replaced with \return. Signed-off-by: Abderrahmane JARMOUNI <[email protected]>
Fix how Doxygen special commands \retval & \return are used in doc text. \retval: Starts a description for a function's return value with name <return value>, which needs to be attached and to not a word that is part of the sentence, and each return val should have its own \retval. Otherwise \retval is replaced with \return. Signed-off-by: Abderrahmane JARMOUNI <[email protected]>
Fix how Doxygen special commands \retval & \return are used in doc text. \retval: Starts a description for a function's return value with name <return value>, which needs to be attached and to not a word that is part of the sentence, and each return val should have its own \retval. Otherwise \retval is replaced with \return. Signed-off-by: Abderrahmane JARMOUNI <[email protected]>
Fix how Doxygen special commands \retval & \return are used in doc text. \retval: Starts a description for a function's return value with name <return value>, which needs to be attached and to not be a word that is part of the sentence, and each return val should have its own \retval. Otherwise \retval is replaced with \return. Signed-off-by: Abderrahmane JARMOUNI <[email protected]>
Fix how Doxygen special commands \retval & \return are used in doc text. \retval: Starts a description for a function's return value with name <return value>, which needs to be attached and to not be a word that is part of the sentence, and each return val should have its own \retval. Otherwise \retval is replaced with \return. Signed-off-by: Abderrahmane JARMOUNI <[email protected]>
|
zephyrbot
requested review from
Thalley,
alwa-nordic,
andyross,
bjarki-andreasen,
dcpleung,
hermabe,
jhedberg,
jukkar,
nashif,
pdgendt,
peter-mitsis,
rlubos,
rugeGerritsen,
sjanc and
ssharks
| * @retval true if the two addresses are equal | ||
| * @retval false otherwise |
There was a problem hiding this comment.
Since you are already touching so many @retvals, consider if it makes sense to fully fix some of the issues with @retval in the documentation: #65974
E.g. these need to be
| * @retval true if the two addresses are equal | |
| * @retval false otherwise | |
| * @retval true The two addresses are equal | |
| * @retval false The two addresses are not equal |
There was a problem hiding this comment.
There was a 1st attempt in #97876, but closed it since the changes seemed to be somewhat controversial & it was going to take considerable time to address each case individually.
Thalley
left a comment
Thalley
left a comment
There was a problem hiding this comment.
I'm not objecting to the changes in this PR; it's probably an overall improvement and it certainly fixes a lot of formatting issues.
However, some of the changes from retval => return does seem like a step in the wrong direction, and a proper fix for the documentation of return values would have been better. Chances are that some of the changes here would have to be reverted back to retval, or that some of the retvalsshould be removed and the text moved to thereturn`.
| * @return Number of bytes copied on success | ||
| * @retval ISOTP_RECV_TIMEOUT when "timeout" timed out | ||
| * @retval ISOTP_N_* on error |
There was a problem hiding this comment.
It's a bit curious to use both @return and @retval, but I guess it works:
Although it may be better to have something like
(from e.g. https://man7.org/linux/man-pages/man2/send.2.html)
i.e. making it clear that it either returns a value, or a set of errors. I don't see anything in doxygen that supports this though - @kartben thoughts?
There was a problem hiding this comment.
It's a bit curious to use both @return and @RetVal, but I guess it works
Yeah the combination of @return and @retval probably looks "wrong" at first sight, but I do think it's actually great. See here.
i.e. making it clear that it either returns a value, or a set of errors. I don't see anything in doxygen that supports this though - @kartben thoughts?
Yeah probably not supported. I think "Returns" vs. "Returns values" is already not so bad though?
There was a problem hiding this comment.
I think "Returns" vs. "Returns values" is already not so bad though?
I don't think it is bad, I just think "Return Value" and "Errors" is better :)
| * @retval 0 if successful. | ||
| * @retval -EINVAL if any provided cellular network configuration is invalid or unsupported. | ||
| * @retval -ENOTSUP if API is not supported by cellular network device. | ||
| * @retval Negative errno-code otherwise. | ||
| * @retval <0 Negative errno-code otherwise. |
There was a problem hiding this comment.
This is also a bit weird where only a subset of the error codes are defined.
7 participants
Fix how Doxygen special command \retval is used in APIs doc text.
\retval: Starts a description for a function's return value with name
<return value>, which needs to be attached and to not be a word that is part of the sentence, and each return value should have its own \retval.Otherwise \retval is replaced with \return.
See https://www.doxygen.nl/manual/commands.html#cmdreturn
https://www.doxygen.nl/manual/commands.html#cmdretval
https://docs.rtems.org/docs/main/eng/coding-doxygen.html
Doc preview https://builds.zephyrproject.io/zephyr/pr/98324/docs/doxygen/html/topics.html